<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Pin: Fast Buffering APIs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Pin
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#typedef-members">Typedefs</a> &#124;
<a href="#func-members">Functions</a> &#124;
<a href="#var-members">Variables</a>  </div>
  <div class="headertitle">
<div class="title">Fast Buffering APIs<div class="ingroups"><a class="el" href="group__API__REF.html">Instrumentation API Reference</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:gab76ee2f4d8b082ba5a3d736279b823db"><td class="memItemLeft" align="right" valign="top">typedef VOID *(*&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__BUFFER.html#gab76ee2f4d8b082ba5a3d736279b823db">TRACE_BUFFER_CALLBACK</a>) (<a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a> id, <a class="el" href="group__THREADS.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid, const <a class="el" href="structCONTEXT.html">CONTEXT</a> *ctxt, VOID *buf, UINT64 numElements, VOID *v)</td></tr>
<tr class="separator:gab76ee2f4d8b082ba5a3d736279b823db"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaee232a4179b4897b5869a6d5fc98d032"><td class="memItemLeft" align="right" valign="top">typedef UINT32&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a></td></tr>
<tr class="separator:gaee232a4179b4897b5869a6d5fc98d032"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga56fa8ed5b1b58950a46f5bab942adfb8"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__BUFFER.html#ga56fa8ed5b1b58950a46f5bab942adfb8">PIN_DefineTraceBuffer</a> (size_t recordSize, UINT32 numPages, <a class="el" href="group__BUFFER.html#gab76ee2f4d8b082ba5a3d736279b823db">TRACE_BUFFER_CALLBACK</a> fun, VOID *val)</td></tr>
<tr class="separator:ga56fa8ed5b1b58950a46f5bab942adfb8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga621843095c4669fd6511046b4acbe436"><td class="memItemLeft" align="right" valign="top">VOID *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__BUFFER.html#ga621843095c4669fd6511046b4acbe436">PIN_AllocateBuffer</a> (<a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a> id)</td></tr>
<tr class="separator:ga621843095c4669fd6511046b4acbe436"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4f86704278faf1b37c8a04e9214bd499"><td class="memItemLeft" align="right" valign="top">VOID&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__BUFFER.html#ga4f86704278faf1b37c8a04e9214bd499">PIN_DeallocateBuffer</a> (<a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a> id, VOID *buf)</td></tr>
<tr class="separator:ga4f86704278faf1b37c8a04e9214bd499"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga0122fc5da88c6a77997475b1a6f74a45"><td class="memItemLeft" align="right" valign="top">VOID *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__BUFFER.html#ga0122fc5da88c6a77997475b1a6f74a45">PIN_GetBufferPointer</a> (<a class="el" href="structCONTEXT.html">CONTEXT</a> *const ctxt, <a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a> id)</td></tr>
<tr class="separator:ga0122fc5da88c6a77997475b1a6f74a45"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="var-members"></a>
Variables</h2></td></tr>
<tr class="memitem:gaf379010b4b5cf3316089bb041ce5c02b"><td class="memItemLeft" align="right" valign="top">const <a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__BUFFER.html#gaf379010b4b5cf3316089bb041ce5c02b">BUFFER_ID_INVALID</a> = 0</td></tr>
<tr class="separator:gaf379010b4b5cf3316089bb041ce5c02b"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>APIs to perform low-overhead buffering of data for analysis. Use <a class="el" href="group__BUFFER.html#ga56fa8ed5b1b58950a46f5bab942adfb8">PIN_DefineTraceBuffer()</a> to create space for storing data, and <a class="el" href="group__INS__INSTRUMENTATION.html#ga097198320639318c65fa1ee815cbbe0c">INS_InsertFillBuffer()</a> to fill the buffers. When a buffer overflows, or the thread exits, the defined callback will be used to process the data. </p>
<h2 class="groupheader">Typedef Documentation</h2>
<a id="gaee232a4179b4897b5869a6d5fc98d032"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaee232a4179b4897b5869a6d5fc98d032">&#9670;&nbsp;</a></span>BUFFER_ID</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">typedef UINT32 <a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Tool buffer ID assigned by Pin. </p>

</div>
</div>
<a id="gab76ee2f4d8b082ba5a3d736279b823db"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gab76ee2f4d8b082ba5a3d736279b823db">&#9670;&nbsp;</a></span>TRACE_BUFFER_CALLBACK</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">typedef VOID*(* TRACE_BUFFER_CALLBACK) (<a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a> id, <a class="el" href="group__THREADS.html#ga645289be59039349ad77ad2fa7b0e2f3">THREADID</a> tid, const <a class="el" href="structCONTEXT.html">CONTEXT</a> *ctxt, VOID *buf, UINT64 numElements, VOID *v)</td>
        </tr>
      </table>
</div><div class="memdoc">
<p>A call-back function which Pin calls whenever the tools needs to consume a trace buffer (e.g., the trace buffer is full).</p>
<p>@Note This function may be called on a different thread than the given threadIndex.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>The ID of the trace buffer. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">tid</td><td>The ID of the thread owning this buffer. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">buf</td><td>Pointer to the start of the buffer. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">numElements</td><td>The number of elements collected into the buffer which need to be consumed. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">v</td><td>The tool's call-back value.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A pointer to the buffer to use when the thread resumes. Typically, this is <em>buf</em>, but see also <a class="el" href="group__BUFFER.html#ga621843095c4669fd6511046b4acbe436">PIN_AllocateBuffer()</a>. </dd></dl>

</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga621843095c4669fd6511046b4acbe436"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga621843095c4669fd6511046b4acbe436">&#9670;&nbsp;</a></span>PIN_AllocateBuffer()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID* PIN_AllocateBuffer </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a>&#160;</td>
          <td class="paramname"><em>id</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Explicitly allocate a trace buffer. This is only needed for tools which use a "double buffering" technique. When used, the buffer pointer should be returned from the TRACE_BUFFER_CALLBACK call-back.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>The ID of the trace buffer to allocate.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>A pointer to the new buffer.]</dd></dl>
<dl class="section note"><dt>Note</dt><dd>The pin client lock is obtained during the call of this API.</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: Linux &amp; Windows<br  />
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br  />
</dd></dl>

</div>
</div>
<a id="ga4f86704278faf1b37c8a04e9214bd499"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga4f86704278faf1b37c8a04e9214bd499">&#9670;&nbsp;</a></span>PIN_DeallocateBuffer()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID PIN_DeallocateBuffer </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a>&#160;</td>
          <td class="paramname"><em>id</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">VOID *&#160;</td>
          <td class="paramname"><em>buf</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Explicitly deallocate a trace buffer. This is only needed by tools using a "double buffering" technique, where it is used to deallocate buffers allocated via <a class="el" href="group__BUFFER.html#ga621843095c4669fd6511046b4acbe436">PIN_AllocateBuffer()</a>. However, it may be safely called (with no effect) for a thread's implicit initial buffer.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>The ID of the trace buffer. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">buf</td><td>Pointer to the start of the buffer.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The pin client lock is obtained during the call of this API.</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: Linux &amp; Windows<br  />
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br  />
</dd></dl>

</div>
</div>
<a id="ga56fa8ed5b1b58950a46f5bab942adfb8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga56fa8ed5b1b58950a46f5bab942adfb8">&#9670;&nbsp;</a></span>PIN_DefineTraceBuffer()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a> PIN_DefineTraceBuffer </td>
          <td>(</td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>recordSize</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">UINT32&#160;</td>
          <td class="paramname"><em>numPages</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="group__BUFFER.html#gab76ee2f4d8b082ba5a3d736279b823db">TRACE_BUFFER_CALLBACK</a>&#160;</td>
          <td class="paramname"><em>fun</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">VOID *&#160;</td>
          <td class="paramname"><em>val</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Define a trace buffer to use with the Pin trace buffer API. This function defines the shape of the buffer, but doesn't allocate the buffer itself. Each thread implicitly creates its first buffer on start-up. Additional buffers may then be created using <a class="el" href="group__BUFFER.html#ga621843095c4669fd6511046b4acbe436">PIN_AllocateBuffer</a>, but this is only needed by tools using "double buffering".</p>
<p>Upon exit, the notification callback may be called on a different physical thread than the one that is exiting.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">recordSize</td><td>Size (bytes) of each record in the buffer. This size must be less than the size of an OS page. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">numPages</td><td>The number of OS pages to allocate for each buffer. This size does not have to be an even multiple of <em>recordSize</em>. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">fun</td><td>A call-back function that is called whenever the buffer is full, or when the thread exits with a partially-full buffer. Note that when called for a full buffer, not during thread exit, this function is called WITHOUT holding any Pin locks. So that multiple threads may be executing the function simultaneously. It is the tool's responsibility to take care of the multi-thread safety of this function, and any functions called by it. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">val</td><td>Passed as the last argument to <em>fun</em>.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>On success, a BUFFER_ID. On error (e.g., maximum number of trace buffers exceeded,) returns BUFFER_ID_INVALID.</dd></dl>
<dl class="section note"><dt>Note</dt><dd>The vm and pin client locks are obtained during the call of this API.</dd></dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: Linux &amp; Windows<br  />
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br  />
</dd></dl>

</div>
</div>
<a id="ga0122fc5da88c6a77997475b1a6f74a45"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga0122fc5da88c6a77997475b1a6f74a45">&#9670;&nbsp;</a></span>PIN_GetBufferPointer()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID* PIN_GetBufferPointer </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="structCONTEXT.html">CONTEXT</a> *const&#160;</td>
          <td class="paramname"><em>ctxt</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a>&#160;</td>
          <td class="paramname"><em>id</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the address of the current position in the buffer. Needs a <a class="el" href="structCONTEXT.html">CONTEXT</a> that was passed in as a call back argument or IARG_CONTEXT</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">id</td><td>The ID of the trace buffer. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">ctxt</td><td><a class="el" href="structCONTEXT.html">CONTEXT</a></td></tr>
  </table>
  </dd>
</dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: Linux &amp; Windows<br  />
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br  />
</dd></dl>

</div>
</div>
<h2 class="groupheader">Variable Documentation</h2>
<a id="gaf379010b4b5cf3316089bb041ce5c02b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaf379010b4b5cf3316089bb041ce5c02b">&#9670;&nbsp;</a></span>BUFFER_ID_INVALID</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">const <a class="el" href="group__BUFFER.html#gaee232a4179b4897b5869a6d5fc98d032">BUFFER_ID</a> BUFFER_ID_INVALID = 0</td>
        </tr>
      </table>
</div><div class="memdoc">
<p>ID returned if defining a buffer fails. </p>

</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
